fix(chunk-grids): make array creation O(1) in per-dimension chunk count - #4218

Chunk normalization now returns a ChunkGrid whose uniform dimensions are
stored as FixedDimension (size + extent) instead of one array entry per
chunk, so create_array(shape=(2**62,), chunks=(1,)) succeeds instantly
instead of raising "array is too big", and chunks=(1, 1) on a
(2**31, 2**31) array no longer allocates ~17 GB per dimension.

Explicit per-chunk lists collapse to FixedDimension when they describe a
regular grid; genuinely irregular lists become VaryingDimension. Both
variants bind chunk sizes to their extent, so the two forms carry the
same invariants. The intermediate ChunksTuple type and as_regular_shape
helper are removed; create_chunk_grid_metadata consumes the grid
directly and serializes uniform dimensions of mixed rectilinear grids
as the spec's bare-int step-size shorthand.

Creation-time counterpart of the zarr-developersgh-4174 indexing fix.

Assisted-by: ClaudeCode:claude-fable-5

Drop the regular-grid collapse for explicit list input in
normalize_chunks_1d: a per-chunk size list now always produces
VaryingDimension, even when the sizes are uniform or uniform plus a
short tail. Scalar specs (ints, numpy integers, and the -1 sentinel)
still produce FixedDimension, which is the path that makes array
creation O(1) in per-dimension chunk count; explicit lists are already
O(n) in the input, so nothing is lost.

The grid kind now follows the input syntax, matching 3.2.x behavior:
previously an explicitly rectilinear spec whose edges happened to look
regular was silently stored as RegularChunkGridMetadata, which changes
resize semantics — a regular grid grows by extending the uniform
pattern while a rectilinear grid appends an edge chunk, breaking
append-oriented layouts like (168,) * 13 + (24,). This is resolution
option 1 from zarr-developersgh-4272.

Uniform dimensions of mixed scalar/list specs still serialize as the
spec's bare-int step-size shorthand; explicit lists serialize as edge
lists.

The touched-chunk-keys assertions in the resize regression test follow
the approach from zarr-developersgh-4290, which fixes the same issue on main via a
requested_rectilinear flag.

Fixes zarr-developers#4272

Co-authored-by: Shurong Cao <CAOShurong@users.noreply.github.com>
Assisted-by: ClaudeCode:claude-fable-5

…me grid

The stateful hypothesis tests in CI failed in from_array on a
rectilinear source whose edges happen to be uniform (e.g.
chunk_shapes=((3,),)): _parse_keep_array_attr and _info guarded
data.chunks / data.shards with the runtime ChunkGrid.is_regular, but
the runtime grid collapses uniform rectilinear dimensions to
FixedDimension as an optimization, while metadata.chunks raises for
any array whose stored grid is rectilinear. Before explicit per-chunk
lists stopped collapsing at creation, the two notions of regularity
always agreed for created arrays, so the mismatch was unreachable.

Add _stored_chunk_grid_is_regular, which dispatches on the metadata
kind, and use it at the three sites that read .chunks/.shards. A
uniform-edged rectilinear source now round-trips through from_array
with its grid kind intact.

Assisted-by: ClaudeCode:claude-fable-5

… restore iteration bounds checks

Addresses maxrjones's second review round on zarr-developers#4218:

- from_array with chunks='keep' / shards='keep' failed on sources shrunk
  by resize: the stored grid legally keeps trailing edges beyond the
  extent, but the keep path re-validated it through the strict
  user-spec parser. ChunksLike/ShardsLike now admit a stored
  ChunkGridMetadata, which normalize_chunks_nd accepts under the
  tolerant from_sizes rules and init_array stores verbatim — the keep
  path passes the grid object itself, so the copy preserves the stored
  grid exactly. This also fixes the last fidelity gap: an
  externally-written rectilinear grid using bare-int shorthand on every
  dimension no longer degrades to a regular grid.
- _iter_shard_regions silently truncated out-of-bounds selections after
  the switch to ChunkGrid.iter_chunk_regions, while its sibling
  _iter_shard_keys raises. all_chunk_coords now applies the same bounds
  check as _iter_grid, so both APIs fail loudly and consistently.
- _is_rectilinear_chunks only sampled the first element, so mixed
  per-dimension specs with a bare int first bypassed the v2 and
  chunks+shards gates and died later on an internal error. It now scans
  all dimensions (and recognizes rectilinear grid metadata).
- _nchunks_initialized walked every shard coordinate even for regular
  shard grids; the O(1) multiply is restored there, and rectilinear
  shard grids now decode only the initialized keys instead of scanning
  the full grid.
- The zarr-developers#4174 changelog entry no longer claims zarr-developers#4172 as the full indexing
  counterpart; the coordinate-selection allocation stays tracked in
  zarr-developers#4174.

FROM_ARRAY_KEEP_CASES gains shrunk rectilinear and shrunk
rectilinear-sharded rows, plus tests for the bounds check, the
order-independent gates, the regular-sharded multiply agreeing with the
per-shard sum, and the all-bare-int keep round-trip.

Assisted-by: ClaudeCode:claude-fable-5

- Contrast read_chunk_sizes and write_chunk_sizes in their docstring
  examples with a sharded array where the two differ (the previous
  examples were identical, which is what prompted the question), and
  route read_chunk_sizes through the _sharding_codec helper.
- Validate scalar chunk sizes before handling the -1 sentinel, with an
  error message that names -1 as valid.
- Rename _stored_rectilinear_grid to _stored_rectilinear_grid_or_none.
- User guide: state why inner chunks are always regular (the sharding
  codec requires a uniform inner chunk shape).
- Changelog: make explicit that everything in the entry sits behind the
  experimental rectilinear feature flag.

Assisted-by: ClaudeCode:claude-fable-5